package paskal.audio.player;

import java.util.Map;

/**
 * This interface defines callbacks methods that will be notified for all
 * registered PlayerListener of Player.
 */
public interface PlayerListener {
	/**
	 * Open callback, stream is ready to play.
	 * 
	 * properties map includes audio format dependant features such as bitrate,
	 * duration, frequency, channels, number of frames, vbr flag, id3v2/id3v1
	 * (for MP3 only), comments (for Ogg Vorbis), ...
	 * 
	 * @param stream
	 *            could be File, URL or InputStream
	 * @param properties
	 *            audio stream properties.
	 */
	public void onOpened(Object stream, Map<String, Object> properties);

	/**
	 * Progress callback while playing.
	 * 
	 * This method is called severals time per seconds while playing. properties
	 * map includes audio format features such as instant bitrate, microseconds
	 * position, current frame number, ...
	 * 
	 * @param bytesread
	 *            from encoded stream.
	 * @param microseconds
	 *            elapsed (<b>reseted after a seek !</b>).
	 * @param pcmdata
	 *            PCM samples.
	 * @param properties
	 *            audio stream parameters.
	 */
	public void onRunning(double percentagePosition,
			Map<String, Object> properties);

	/**
	 * Progress callback while cashing.
	 * 
	 * This method is called severals time per seconds while loading.
	 * 
	 * @param properties
	 *            audio stream parameters.
	 */
	public void onLoading(double percentage);

	/**
	 * Notification callback for basicplayer events such as opened, eom ...
	 * 
	 * @param event
	 */
	public void onStateUpdated(PlayerEvent event);
}